gh-141510, PEP 814: Add built-in frozendict type by vstinner · Pull Request #144757 · python/cpython

vstinner · 2026-02-12T18:21:35Z

Add TYPE_FROZENDICT to the marshal module.

Add C API functions:

PyAnyDict_Check()
PyAnyDict_CheckExact()
PyFrozenDict_Check()
PyFrozenDict_CheckExact()
PyFrozenDict_New()

Add PyFrozenDict_Type C type.

Issue: PEP 814: Add built-in frozendict type #141510

📚 Documentation preview 📚: https://cpython-previews--144757.org.readthedocs.build/en/144757/c-api/dict.html#frozen-dictionary-objects

Add TYPE_FROZENDICT to the marshal module. Add C API functions: * PyAnyDict_Check() * PyAnyDict_CheckExact() * PyFrozenDict_Check() * PyFrozenDict_CheckExact() * PyFrozenDict_New() Add PyFrozenDict_Type C type.

vstinner · 2026-02-13T07:49:35Z

cc @corona10

Fix also indentation.

Doc/library/stdtypes.rst

Doc/whatsnew/3.15.rst

Lib/test/mapping_tests.py

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Objects/dictobject.c

corona10 · 2026-02-13T13:00:43Z

Objects/dictobject.c

    }

-    if (PyDict_CheckExact(d)) {
+    if (PyAnyDict_CheckExact(d)) {


Maybe same opinion with @kumaraditya303 we can avoid a lot of critical section if dict is frozen dict.

I agree, but I would prefer to make such "optimization" change in a separated PR.

corona10 · 2026-02-13T13:01:28Z

Objects/dictobject.c

 dict_length(PyObject *self)
 {
-    return FT_ATOMIC_LOAD_SSIZE_RELAXED(((PyDictObject *)self)->ma_used);
+    return GET_USED(_PyAnyDict_CAST(self));


Do we have to use atomic operation for frozendict?

No, we can skip the atomic operation for frozendict.

It uses relaxed atomic so it compiles to simple loads so avoiding it has no real benefit.

corona10 · 2026-02-13T13:02:04Z

Objects/dictobject.c

+};
+
+static PyMappingMethods frozendict_as_mapping = {
+    .mp_length = dict_length,


I think that we can make frozendict_lenth

I propose to make such optimization in a separated PR.

corona10 · 2026-02-13T13:05:55Z

Objects/dictobject.c

+
+static PyMappingMethods frozendict_as_mapping = {
+    .mp_length = dict_length,
+    .mp_subscript = dict_subscript,


Still perfer to make frozendict_subscript, but let's do it at the separate PR.

corona10

We should notice that frozendict is not subclass of dict to follow SC feedback

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Document frozendict after lazy import.

vstinner · 2026-02-13T15:02:44Z

Objects/dictobject.c

            mp->ma_values == NULL &&
-            (mp->ma_used >= (mp->ma_keys->dk_nentries * 2) / 3))
+            (mp->ma_used >= (mp->ma_keys->dk_nentries * 2) / 3) &&
+            !frozendict)


We might take this fast-path for frozendict as well. It's just a missed optimization opportunity.

@corona10: Add it to the optimization TODO list :-)

Yeah I will take a look at it

vstinner · 2026-02-13T15:07:01Z

Objects/dictobject.c

+    if (items == NULL) {
+        return -1;
+    }
+    PyObject *frozenset = PyFrozenSet_New(items);


The current implementation creates an actual frozenset object which emits surprising error messages:

>>> hash(frozendict(x=[])) Traceback (most recent call last): File "<python-input-0>", line 1, in <module> hash(frozendict(x=[])) ~~~~^^^^^^^^^^^^^^^^^^ TypeError: cannot use 'tuple' as a set element (unhashable type: 'list')

We may change the implementation later to not create an actual frozenset, but reuse frozenset hash code instead, to avoid the surprising errors.

vstinner · 2026-02-13T15:13:01Z

We should notice that frozendict is not subclass of dict to follow SC feedback

Ah right, done.

bedevere-bot · 2026-02-14T12:19:13Z

🤖 New build scheduled with the buildbot fleet by @corona10 for commit 9101b1a 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F144757%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-refleak-buildbots label again.

corona10 · 2026-02-14T12:19:43Z

Let's wait build bot to pass the refleak test :)

benediktjohannes

Nitpick: I know this does not primarily belong to the PR, but it's such a small change that a new PR wouldn't make sense for these small "typos".

Doc/library/stdtypes.rst

Co-authored-by: Adam Johnson <me@adamj.eu>

vstinner · 2026-02-16T10:53:00Z

Let's wait build bot to pass the refleak test :)

Tests passed successfully on Refleaks buildbots:

buildbot/AMD64 CentOS9 NoGIL Refleaks PR — Build done.
buildbot/AMD64 Fedora Stable Refleaks PR — Build done.
buildbot/AMD64 FreeBSD Refleaks PR — Build done.
buildbot/AMD64 RHEL8 Refleaks PR — Build done.
buildbot/AMD64 Windows11 Refleaks PR — Build done.
buildbot/ARM64 MacOS M1 Refleaks NoGIL PR — Build done.
buildbot/PPC64LE Fedora Stable Refleaks PR — Build done.
buildbot/PPC64LE RHEL8 Refleaks PR — Build done.
buildbot/s390x Fedora Stable Refleaks PR — Build done.
buildbot/s390x RHEL8 Refleaks PR — Build done.
buildbot/s390x RHEL9 Refleaks PR — Build done.

Doc/c-api/dict.rst

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Add also a title in Doc/library/stdtypes.rst.

vstinner · 2026-02-16T12:16:21Z

@hugovk: I modified a few more titles in the C API doc and the Python doc to use sentence case for headers.

pythongh-141510, PEP 814: Add built-in frozendict type

bde4379

Add TYPE_FROZENDICT to the marshal module. Add C API functions: * PyAnyDict_Check() * PyAnyDict_CheckExact() * PyFrozenDict_Check() * PyFrozenDict_CheckExact() * PyFrozenDict_New() Add PyFrozenDict_Type C type.

bedevere-app bot mentioned this pull request Feb 12, 2026

PEP 814: Add built-in frozendict type #141510

Open

vstinner added 2 commits February 12, 2026 19:25

Document PyFrozenDict_Type in the C API doc

1fb7c5a

Fix test_inspect and test_doctest

fca2e5b

vstinner marked this pull request as ready for review February 13, 2026 07:30

vstinner requested review from AA-Turner, ZeroIntensity, ericsnowcurrently, markshannon, methane and rhettinger as code owners February 13, 2026 07:30

bedevere-app bot added the awaiting core review label Feb 13, 2026

Complete the documentation

99b291c

vstinner mentioned this pull request Feb 13, 2026

[WIP] gh-141510: PEP 814: Add built-in frozendict type #141508

Draft

Fix doc warnings

5e4a284

Fix also indentation.

corona10 self-requested a review February 13, 2026 10:07

hugovk reviewed Feb 13, 2026

View reviewed changes

Apply suggestions from code review

5c0c6f1

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

kumaraditya303 reviewed Feb 13, 2026

View reviewed changes

Objects/dictobject.c Show resolved Hide resolved

corona10 reviewed Feb 13, 2026

View reviewed changes

vstinner and others added 3 commits February 13, 2026 15:46

Apply suggestion from @hugovk

8d4ed14

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Move the What's New entry

c770613

Document frozendict after lazy import.

Revert _PyDict_LoadBuiltinsFromGlobals() change

6dfec48

vstinner commented Feb 13, 2026

View reviewed changes

Document that frozendict is not a dict subclass

9101b1a

corona10 added the 🔨 test-with-refleak-buildbots Test PR w/ refleak buildbots; report in status section label Feb 14, 2026

bedevere-bot removed the 🔨 test-with-refleak-buildbots Test PR w/ refleak buildbots; report in status section label Feb 14, 2026

benediktjohannes reviewed Feb 14, 2026

View reviewed changes

Doc/library/stdtypes.rst Show resolved Hide resolved

Doc/library/stdtypes.rst Show resolved Hide resolved

Doc/library/stdtypes.rst Show resolved Hide resolved

adamchainz reviewed Feb 15, 2026

View reviewed changes

Doc/library/stdtypes.rst Outdated Show resolved Hide resolved

Update Doc/library/stdtypes.rst

e845b2b

Co-authored-by: Adam Johnson <me@adamj.eu>

hugovk reviewed Feb 16, 2026

View reviewed changes

vstinner and others added 2 commits February 16, 2026 13:01

Apply suggestions from code review

3d08f46

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

doc: use sentence case for headers

258b3df

Add also a title in Doc/library/stdtypes.rst.

Uh oh!

Conversation

vstinner commented Feb 12, 2026 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Feb 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

corona10 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vstinner commented Feb 13, 2026

Uh oh!

bedevere-bot commented Feb 14, 2026

Uh oh!

corona10 commented Feb 14, 2026

Uh oh!

benediktjohannes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vstinner commented Feb 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vstinner commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

vstinner commented Feb 12, 2026 •

edited by hugovk

Loading